docs: add FilterState typedef and annotate filter-passing functions#39
Merged
mekarpeles merged 2 commits intomainfrom Apr 27, 2026
Merged
docs: add FilterState typedef and annotate filter-passing functions#39mekarpeles merged 2 commits intomainfrom
mekarpeles merged 2 commits intomainfrom
Conversation
closes #35 Adds a @typedef {Object} FilterState in utils/filters.js documenting all seven fields (sort, availability, fictionFilter, languages, genres, authors, subjects) with accepted value ranges. Annotates buildChips and buildSearchParams with @param {FilterState} and @returns. Four static-analysis tests verify the typedef and annotations exist so they stay in sync if the filter shape changes.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds JSDoc typing for the shared “filter state” object to improve editor IntelliSense and documentation around filter-related utilities.
Changes:
- Introduces a
FilterStateJSDoc typedef infrontend/src/utils/filters.jsdescribing the 7 filter fields. - Annotates
buildChipsandbuildSearchParamswith@param {FilterState}(and adds@returns). - Adds Vitest “static analysis” tests that assert the typedef and key annotations exist in the source.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
frontend/src/utils/filters.js |
Adds FilterState typedef and JSDoc annotations for filter utility functions. |
frontend/src/utils/filters.test.js |
Adds static-analysis tests that regex-check the presence of typedef and annotations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- FilterState @Property annotations now use JSDoc string-literal unions for sort/availability/fictionFilter and mark array fields as optional ([languages], [genres], [authors], [subjects]) to match runtime usage - buildChips docstring corrected: availability and fiction chips use plain descriptive labels, not "type: value" prefix (only lang/genre/ author/subject use the prefix) - Added a 4th static-analysis test verifying literal-union types are present in the FilterState typedef
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #35
What
Adds
@typedef {Object} FilterStatetoutils/filters.jswith a@propertyline for each of the seven filter fields and their accepted value ranges. AnnotatesbuildChipsandbuildSearchParamswith@param {FilterState}and@returns.Why
The filter object is the primary data structure passed between
ol-search-bar,ol-search-page, and the utils layer. Without a typedef, editors give no autocomplete or type errors when callers pass the wrong shape. New contributors have to read all consumers to discover what keys exist.Verified by
Four new static-analysis tests in
filters.test.js:@typedef {Object} FilterStateexists in the source@propertyentries@param {FilterState}annotations exist (buildChips + buildSearchParams)No behavioral changes — 170 tests pass, lint clean.